home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Ian & Stuart's Australian Mac 1
/
Ian and Stuart's One (Australia).iso
/
Australasian Legends
/
Commercial
/
Rainbow Hill
/
MacDOS™ 2.0.0
/
User's Guide
/
13.2 DIR - INCR
< prev
next >
Wrap
Text File
|
1994-09-20
|
32KB
|
767 lines
DIR
lists the contents of a folder (ie. a DIRectory).
Syntax
dir [selection] [/[-]A[[:]attribute list]] [/[-]B]
[/C=creator] [/[-]L] [/[-]O[[:]ordering list]] [/[-]P] [/[-
]S] [/T=file type] [/[-]W]
Parameters
selection
is a name preceded by an absolute or relative path which
specifies the items to be listed. A group of files is
identified via a wildcarded filename or a folder name. If
selection is omitted, DIR lists the contents of the current
folder.
Switches
/[-]A[[:]attribute list]
only lists items with attributes included in the
attribute list (but look at the note concerning DIRCMD).
The attribute list is a string of single letter attributes:
D for Directories,
F for visible Files,
H for Hidden files,
X for aliases.
A minus sign preceding an attribute tells MacDOS not to
list items with that attribute. A minus sign between the /
and the A inverts the logic of all attributes in the
attribute list. By default, MacDOS does not list hidden
files.
/B
lists item names one per line and without headings (bare
format). When the /S option is also ON, /B writes the full
path instead of the item name only. A minus sign between
the / and the B switches this option OFF.
/C=creator
specifies that only files of a particular creator are to be
listed. Note that no spaces are allowed on either side of
the equal sign and that the creator string is four
characters long. Therefore, if a creator includes spaces,
you must double quote the switch (eg. dir \ "/c=ABC " lists
all the files created by 'ABC ' in the root folder).
/L
operates case-sensitive matching on the selection. A minus
sign between the / and the L switches this option OFF.
[/[-]O[[:]ordering list]]
sorts the items as specified in the ordering list before
listing them. The ordering list is a string of single
letter sorting criteria:
D by Date & time of update (older first)
G Group directories first
N by Name (alphabetic)
S by Size (smallest first)
A minus sign preceding a sorting criterion tells MacDOS to
sort in the reverse order. A minus sign between the / and
the O inverts the logic of all criteria in the
ordering list.
/P
pauses after each screenful of listing. A minus sign
between the / and the P switches this option OFF.
/S
provides a recursive display of the items in all
subfolders. A minus sign between the / and the S switches
this option OFF.
/T=file type
specifies that only files of a particular type (eg. TEXT)
are to be listed. Note that no spaces are allowed on either
side of the equal sign and that the file type is four
characters long. Therefore, if a file type includes spaces,
you must double quote the switch (eg. dir \ "/t=ABC " lists
all the files of type 'ABC ' in the root folder).
/W
lists item names in a wide format, with as many items per
line as possible. A minus sign between the / and the W
switches this option OFF.
MacDOS vs DOS
Switches
The switches /AS, /AA, /AR, and /OE are not implemented,
but /AF, /AX, /C, and /T have been introduced.
Directory header
To cope with the long names typical of the Mac, the path in
the directory header is displayed with one directory name
per line.
Names containing spaces
All names displayed are quoted, so that leading and
trailing spaces are made visible. Use the system variable
QUOTE to change the quoting character.
Creators and File Types
Creator and file-type are displayed.
Listing of aliases
Target volume and target filename of aliased items are
displayed immediately after the directory entry for the
alias file itself.
Date and time formats
Date and time are displayed in the format chosen by you
(refer to the two commands DATE and TIME).
Notes
DIRCMD
Before executing the command DIR, MacDOS selects the
switches contained in the system variable DIRCMD.
Therefore, DIRCMD represents the system default switches.
You can override the defaults by explicitly including
switches in the command (/-B negates /B, /W negates /-W,
etc.). Alternatively, you can SET DIRCMD to your own
preferred defaults. For instance, you can include /AH so
that hidden files are always displayed. By including such a
SET command in the autoexec.bat file, you only need to type
your preferred defaults once. The system defaults are:
/-P do not pause at the end of each page
/-W do not list in wide format
/A:-HDXF list directories, aliases, and files, but not
hidden files
/-O do not sort
/-S list only the current folder (not recursively)
/-B do not list in bare format
/-L operate case-insensitive
Repetition of switches in the same command
Switches can be repeated. As MacDOS scans the switches from
left to right, the rightmost switch of a particular type
overrides the preceding ones. /A and /O can be repeated to
extend their sub-option lists. For example, /A-H-D is
totally equivalent to /A-H/A-D.
Conflicting attributes in the attribute list
MacDOS scans the attributes of the /A switch from left to
right. Therefore, the rightmost attribute of a particular
type takes effect. For example, /A:HDF-H does not display
hidden files. If you type /-ADFH (or an equivalent sequence
of attributes) you never get any item listed, because you
exclude both folders and files (aliases are particular
cases of files).
Complex sorting
MacDOS scans the ordering list from left to right.
Therefore, the rightmost sorting is done last. For example,
/O:SN first sorts by size, and then by name. Note that
names are unique. Therefore, if you sort by name, all
preceding sorts become totally irrelevant. A similar
consideration also applies to /O:D, because the time of
update is also almost always unique. The situation is
different when you apply /ON or /OD before applying /OG or
/OS. For example, if you apply /O:NSG, you list the
directories ordered by name followed by the files ordered
by size, with files of the same size in alphabetical order
of their names.
Sorting and recursion
Each folder is sorted individually.
Aliases
Under normal circumstances, DIR displays two lines for each
alias. The first line refers to the alias file itself,
while the second line refers to the target. If the alias
cannot be resolved (perhaps because the target is on a
volume which has not been mounted), DIR reports a warning
and then only displays the first line with an indication
that the file is an alias.
Note that when listing an alias, MacDOS always lists the
corresponding targets, regardless of their type and
visibility.
Memory limitations
DIR saves folder information in dynamically allocated
memory rather than on disk. This speeds up the listing but
limits the number of directory items which MacDOS can
handle. With the current memory partition, this limit is of
approximately 1100 entries. If MacDOS returns the error
"Not enough space in the heap", the only solution (short of
splitting the folder which is causing problems) is to
increase the amount of memory allocated to MacDOS. To do
so, exit MacDOS, click once on the application icon, press
cmd-I, and increment the partition size.
Examples
dir lists the contents of the current
folder.
dir 2:/p lists the contents of the current
folder of volume 2 and pauses at the
end of each page.
dir abc lists the file abc or the contents of
the folder abc contained in the current
folder
dir ..\abc* lists all the items of the parent
folder whose name begins with abc.
dir \/w lists the contents of the root folder
in a wide format.
dir/t=TEXT/s recursively lists all text files in the
current folder and in its subfolders
dir \a\b\*TEMP*/L lists all the files in the folder \a\b
whose name contains the string TEMP
(case sensitive).
dir/o-s/a-d lists the files (not the folders) in
the current folder in order of size
(from the largest to the smallest).
dir \/s/b/c=ABCD/a-d lists all the files on the current
volume created by ABCD. For each item,
the full path and name is given.
dir \t*/s/b/a-f lists all the folder names in the
current volume which start with 't' or
'T'.
dir/a-d-x/s/b>aFile \ saves into a file named aFile the
list of all non-alias files in the
current volume. For each item, the full
path and name is given.
dir /o-d/c=MWII lists all MacWrite II documents in
order of update, from the newest to the
oldest.
dir 1:\/s/b/a-d-fh lists all hidden files on the startup
volume. For each item, the full path
and name is given.
Frequently occurring errors
E27: File or directory not found
Perhaps you specified a proper filename (without wildcards)
but the file does not exist. Alternatively, it is one of
the folders within the path which does not exist.
See Also
TREE
ECHO
displays messages or turns batch command echoing ON and
OFF.
Syntax
echo [{message | ON | OFF}]
echo.
Parameters
{message | ON | OFF}
is a string to be displayed in the MacDOS window. If the
string only consists of the word ON, ECHO does not display
it but enables the echoing of commands to the MacDOS
window. Similarly, OFF causes the echoing to be disabled.
If the parameter is entirely missing, ECHO displays the
current echo setting (ON or OFF).
ECHO immediately followed by a period (a dot) just displays
an empty line.
MacDOS vs DOS
The two implementations are identical.
Notes
Interactive usage
MacDOS lets you use ECHO interactively. Therefore, if you
want to view a single global variable, type ECHO %var%
rather than SET .
Output redirection
ECHO redirects its output when you include it in a batch
program and redirect the output of the whole batch.
EJECT
dismounts and places off-line removable volumes.
Syntax
eject volume [/E]
Parameters
volume
is the ID which identifies the volume to be dismounted or
placed off-line. Without switches, EJECT dismounts the
volume.
Switches
/E
specifies that the volume is only to be placed off-line
(eg. Ejected) without being dismounted.
MacDOS vs DOS
DOS does not support EJECT.
Notes
The start-up volume cannot be dismounted regardless of
whether it is removable or not.
Examples
eject 2:
removes the volume with ID 2. The icon disappears from the
desktop.
eject D /e
ejects the volume D. The icon is then greyed.
EXIT
quits MacDOS, other applications, or the Finder.
Syntax
exit [appl]
exit finder
Parameters
appl
identifies the application that should receive a Quit Apple
Event. If the parameter is missing, MacDOS terminates
itself.
MacDOS vs DOS
In DOS, EXIT is used to quit the current shell and possibly
return to a program which was suspended.
Notes
EXIT's main purpose is to use batch programs as stand-alone
applications which automatically terminate after completing
their task.
Quitting the Finder
When you kill the Finder, you no longer have access to the
items normally in the Apple menu. Be warned that MacDOS
relies on the 'MACS' creator to identify the process
associated with the Finder. If you have already replaced
the Finder with a different application, the "exit finder"
command will have no effect.
You can re-launch the Finder by typing its path/filename as
if it were a normal application. Make an alias of the
Finder, name it F, and place it in a folder included in the
search PATH. You will then be able to then re-launch the
Finder with just two key strokes.
FOR
executes a command or a series of commands for each file in
a set.
Syntax
for %var [/L] in (set) do [command | begin]
Parameters
var
is the name of the variable that FOR uses to store the
names of the files in set, one at a time. When you use the
format "do command", type the string %var where you would
normally type a filename. FOR then executes the command for
all files in the set, one at a time. When you use the
format "do begin", var becomes a global variable rather
than a variable local to FOR. Therefore, type %var% to
obtain the name of the current file.
set
is a list of space-separated items, where each item is
either a file or a folder name. Each item can be preceded
by a volume and path spec, and filenames can be wildcarded.
The parentheses are mandatory.
command | begin
is either the single command to be executed or a keyword
which starts the execution of a series of command lines.
With begin, MacDOS keeps executing command lines until it
encounters a line containing the command NEXT var . At that
point, MacDOS sets var to the next filename in the set and
resumes execution from the line immediately following the
begin. After 'using' all the files in set, MacDOS continues
execution of the batch program from the line immediately
following the NEXT.
Switches
/L
leaves the filenames in the set as they are, without
converting them to uppercase. The default is that the
filenames are converted. This switch must precede the do.
MacDOS vs DOS
Multi-line FORs
The keyword begin allows for loops spanning over more than
one line.
De-referencing the loop control variable
With standard single-line FORs, the control variable is
always de-referenced by prepending a single percent sign
(as in %varName), regardless of whether the FOR is in a
batch program or not. DOS needs a double percent sign in
batch programs. With multi-line loops, the control variable
becomes a standard global variable and is de-referenced
normally (as in %varName%).
Lower case option
DOS does not support /L.
What can be done
Beside normal commands, MacDOS also accepts program names
and the command CALL after the do.
Folder expansion
Folder names in a set are expanded, so that (folderName) in
MacDOS is equivalent to (folderName\*.*) in DOS. This seems
more consistent with the way in which folder names are
usually handled by file-oriented commands.
Notes
Replacing FOR
FOR is a command which has mainly been implemented to help
experienced DOS users. Although it has been extended in a
series of ways, its use remains limited because it does not
distinguish between file types, does not return full paths,
and does not operate recursively. The most flexible way of
operating on a set of files with MacDOS is to use the
following strategy:
• redirect the output of DIR/B to a file (all the
filtering options of DIR as well as its recursive
operation are available);
• OPEN the file;
• repeat the READing of the file, so that a filename at a
time is stored in a global variable and is available for
processing;
• CLOSE the file (only if you do not reach the EOF,
otherwise MacDOS closes the file automatically);
• reSET the global variables used and DELete the file
(always clean-up the mess before you start doing
something else).
Interactive vs. batch
You can execute the standard FOR interactively, while you
can only use the multi-line FOR within batch programs.
What happens to the control variable after exiting the FOR
loop
The control variable of standard single-line FORs is a
local variable and is not accessible within other commands.
On the other hand, the control variable of multi-line FORs
is a normal global variable. After terminating the loop,
such a variable contains the name of the last file in the
set and it is your responsibility to remove it by SETting
it to the empty string. To remove it immediately after
exiting the loop is a good defensive practice.
I/O redirection
Redirection is only legal with the standard single-line
format of FOR. In that case, it applies to the command
which follows the do rather than to the FOR itself.
Piping of the output to other commands is forbidden except
to MORE. To put it simply, FOR only supports piping in the
following case:
FOR %var [/L] IN (set) DO internal-com-with-params |
MORE
Incompatibility of commands
Standard FORs cannot be nested. That is, no FOR command is
allowed after the do keyword of another FOR. IFs are also
forbidden within standard FORs.
Empty set
If the set does not select any file, FORs do not return any
error and multi-line FORs do not create the global
variable.
Running away
If a command within a FOR generates a file which belongs to
the set, a situation in which the loop "feeds" itself with
new files can occur. Such a "runaway" condition would only
stop upon hitting some system boundaries. Here are a couple
of examples:
for %var in (d*) do dir/b > %varX
this command generates a file for each file whose name
begins with the letter 'd'. Unfortunately, the new file
also begins with 'd' and is therefore part of the set.
To see what happens, let's say that you have a file
named DATA. In the first iteration of the FOR-loop,
MacDOS generates DATAX; in the second iteration DATAXX;
then DATAXXX; etc. This only stops when the maximum
length of filenames (31 characters) is reached. If you
had named the new files X%var instead of %varX, you
would have been fine.
set counter=0
for %var in (*t*) do begin
incr counter
copy %var% data%counter%
next var
here the purpose was to make copies of all files
containing the letter 't' and name them data1, data2,
etc. Again, the problem is that the new files are in the
set. New files are probably created until the hard disk
is full. You could have named the new files xxx%counter%
and then renamed them with ren xxx* data* at a later
stage. Alternatively, you could have stored the copies
into a different folder.
The general solution is to replace FOR with a combination
of DIR and a loop. This would avoid the risk of "positive
feedback".
Examples
for %a in (wildcardedFilename) do more < %a
executes a MORE on all files identified by
wildcardedFilename (it only works with files in the current
folder and if they are of type 'TEXT').
for %a in (myDir) do more < myDir\%a
executes a MORE on all files in the folder myDir (it only
works if the files are of type 'TEXT').
Frequently occurring errors
E27: File or directory not found
At least one of the paths specified in the set included a
folder which does not exist.
See Also
NEXT
GOTO
while in batch, continues execution from a labelled line.
Syntax
goto label
Parameters
label
is an alphanumeric string used as a label in the current
batch program. Remember that the colon which identifies the
label is not part of the label itself.
MacDOS vs DOS
The two implementations are identical.
Examples
goto QUIT_LBL
goto 4
GOTO lbl10
goto %var%
Frequently occurring errors
E44: Label not found
The requested label was not defined in the current batch
program.
HELP
provides on-line information for all MacDOS commands.
Syntax
help [entry]
Parameters
entry
is either a command name, a file specification, or a
question mark.
When entry is a command name, HELP displays a description
of the command.
When entry identifies a file, HELP searches the resource
fork of the file looking for a resource of type 'TEXT'
named "help". If it finds it, it display its contents in
the console window. This lets you get help on any program,
filter, and script provided it contains the appropriate
'TEXT' resource.
When entry is a question mark, HELP lists all the command
names.
If entry is missing, HELP lists brief descriptions of all
the commands.
MacDOS vs DOS
The two implementations are identical, except for the fact
that MacDOS supports "HELP ?" and can read "help" text
resources.
IF
performs conditional processing in batch.
Syntax
if [not] {s1 == s1 | exist name | existdir name} command
Parameters
{s1 == s1 | exist name | existdir name}
is a condition which can have three forms:
s1 == s1
is true when the two strings s1 and s2 are identical.
The two strings can contain replaceable parameters and
global variables.
exist name
is true when a file named name exists. The actual
filename can be preceded by a volume specification and
path.
existdir name
is true when a folder named name exists. The actual
folder name can be preceded by a volume specification
and path.
A not preceding a condition changes a true condition to
false and vice versa.
command
is executed when the condition is true. It can be a MacDOS
command or the name of an executable program.
MacDOS vs DOS
Keywords
DOS does not support existdir; MacDOS does not support
errorlevel.
Hidden files
Hidden files exist for MacDOS but not for DOS.
Notes
Aliases
When the item tested with exist or existdir includes a
path, MacDOS resolves all the aliases of folders in the
path but not the innermost one. Therefore, aliases always
satisfy exist and never existdir, regardless of whether the
target is a file or a folder.
Incompatibility with FOR
IFs are not allowed within standard FORs. That is, you
cannot type:
for %var in (set) do if %var == ...
The solution is to use multi-line FORs (or to drop FORs
altogether). Note that you can execute a FOR within an IF.
Reserved words
The words not, exist, and existdir are reserved in both
upper and lower case. Therefore, commands like
if not == %var% are in most cases rejected with a syntax
error. Here is an example in which IF might not do what you
expect:
if not exist == %1 do_this
The purpose is probably to execute do_this if the first
replaceable parameter contains the string "exist".
Unfortunately, IF interprets the command line as a request
to execute "%1 do_this" if a file named "==" does not
exist. Most likely, you do not have such a file. Therefore,
MacDOS will attempt to execute "%1 do_this". This can be
very confusing, especially when you have ECHO disabled. To
avoid this kind of problems, you have the following
choices:
• Never use reserved words (preferred solution).
• Double-quote reserved words and variables which could
contain reserved words:
if "%var%" == "not" do_this
if not "exist" == %1 do_this
Spaces
Spaces within a condition are ignored, unless you double-
quote them. Also, strings containing spaces must be double
quoted.
Examples
Check the existence of a file:
if exist %1 echo file "%1" exists
Check the non-existence of a folder:
if not existdir %1 echo folder "%1" not there
Use a batch program to process all files in a folder, but
only after checking that the folder exists:
if existdir %1 for %file in (%1) do processFile %1\%file
Check the control variable of a loop:
if %counter% == 7 goto EXIT_LOOP_LBL
Check an error condition:
if not %doserr% == 0 goto ERROR_LBL
Frequently occurring errors
E13: Syntax: invalid arguments
Very often this error message is caused by a reference to a
replaceable parameter which was not defined. For example,
if %1 == 3 do_this fails if %1 is empty. It is so because
MacDOS, after replacing %1, only sees if == 3 do_this
and cannot make any sense of it. To avoid this problem,
append a character to both sides of the condition (a space
does not work unless you use double quotes): if %1x == 3x
do_this . Then MacDOS sees if x == 3x do_this and behaves
as expected.
INCR
increments or extends values of global variables.
Syntax
incr [+ | -]var [by {number | string}]
"incr var", equivalent to "incr +var by 1", increments by 1
numeric values and appends one space to the end of
alphanumeric strings.
Parameters
[+ | -]var
is the name of a global variable, possibly preceded by a
plus or a minus sign. No space is allowed between the sign
and the variable name. INCR uses the sign to decide whether
to perform string operations at the end or at the beginning
of var's value.
number
is a signed integer number. INCR uses number differently
depending on whether var contains a numeric value or not:
• When var contains a numeric value, INCR replaces it with
the value obtained after adding number.
• When var contains an alphanumeric string which cannot be
interpreted as a number, INCR extends it by adding
number spaces. The characters are inserted before the
beginning if the variable name is preceded by the minus
sign, otherwise they are appended after its end. When
number is negative, INCR actually shortens the content
of var by removing characters from the end or from the
beginning (depending on the presence of the minus sign
before the variable name).
string
is an alphanumeric string which cannot be interpreted as a
number. INCR joins string to the string contained in var.
The string is prepended if the variable name is preceded by
the minus sign, otherwise the string is appended.
MacDOS vs DOS
DOS does not support INCR.
Notes
Appending numeric characters
When the BY-string is numeric, INCR increments a numeric
variable by that amount or adds that number of spaces to an
alphanumeric variable. If your purpose is to add digits to
a variable (eg. appending '1' to the string "134" so that
it becomes "1341"), you can achieve this result by
extending the BY-string with an alphabetic character and
then immediately removing it from the variable (ie.
INCR var BY 1x followed by DECR var BY x).
Examples
initial var command resulting var
"25" incr var "26"
"25" incr -var "26"
"-25" incr var by 30 "5"
"25" incr var by -3 "22"
"-7" incr var by -30 "-37"
"abcde" incr var "abcde "
"abcde" incr -var " abcde"
"abcde" incr var by 3 "abcde "
"abcde" incr var by -1 "abcd"
"abcde" incr -var by -3 "de"
"ab de" incr var by de "ab dede"
"a cde" incr -var by "a " "a a cde"
"abcde" incr +var by -7 var removed
Frequently occurring errors
E63: Requested variable has not been defined
You attempted to INCRement a variable that did not exist.
Remember that empty variables are automatically removed
unless they are system variables.
See Also
DECR, SSTR, TOUPPER
